Inside Macintosh: QuickTime Components
If your media handler draws media data on the screen, you need to manage your media's graphics environment. The Movie Toolbox uses a number of functions to inform you about changes to the graphics environment. The Movie Toolbox only calls these functions if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.
The Movie Toolbox calls your handler's MediaSetGWorld function whenever your media's graphics port or graphics device has changed. The MediaSetDimensions function allows the Movie Toolbox to inform your handler about changes to its spatial dimensions. Whenever either the movie or track matrix changes, the Movie Toolbox calls your MediaSetMatrix function. Similarly, if your media's clipping region changes, the Movie Toolbox calls your MediaSetClip function.
When it is building up a movie's image from its component tracks, the Movie Toolbox must be able to determine which tracks are transparent. The Movie Toolbox calls your MediaGetTrackOpaque function to retrieve this information about your media.
The Movie Toolbox calls your MediaGetNextBoundsChange function so that it can learn when your media will next change its display shape. When the Movie Toolbox wants to find out the shape of the region into which you draw your media, it calls your MediaGetSrcRgn function.
The MediaSetGWorld function allows your derived media handler to learn about changes to your media's graphic environment.
pascal ComponentResult MediaSetGWorld (MediaHandler mh,
CGrafPtr aPort,
GDHandle aGD);
The Movie Toolbox calls your derived media handler's MediaSetGWorld function whenever your media's graphics world changes. The toolbox provides you with the new graphics port and graphics device. You should then use this information for subsequent graphics operations.
Your derived media handler should support this function if you perform specialized graphics processing or if you are using the Image Compression Manager to decompress your media. Note that when the Movie Toolbox calls your MediaIdle function, it supplies you with information about the current graphics environment. Consequently, you do not need to support the MediaSetGWorld function in order to draw during playback. However, if your media data is compressed and you are using the Image Compression Manager to decompress sequences, you may need to provide updated graphics environment information before playback.
You obtain the initial graphics environment information from the moviePort and movieGD fields of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.
The MediaSetDimensions function allows the Movie Toolbox to inform your media handler when its media's spatial dimensions change.
pascal ComponentResult MediaSetDimensions (MediaHandler mh,
Fixed width,
Fixed height);
The Movie Toolbox calls your derived media handler's MediaSetDimensions function whenever the spatial dimensions of your media's track change. The toolbox provides you with the dimensions of the rectangle that encloses your media's graphical image. Changes to this rectangle may affect the way in which you display your media's data.
You obtain the initial dimension information from the width and height fields of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function (described on MediaInitialize ).
Your derived media handler should support this function if you draw during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function (described on MediaSetHandlerCapabilities ).
The Movie Toolbox uses the MediaSetMatrix function (described in the next section) to tell your media handler about changes to either the movie matrix or the track matrix. In addition, your media handler's MediaSetClip function allows you to learn about changes to your media's clipping region. This function is discussed on MediaSetClip .
The MediaSetMatrix function allows the Movie Toolbox to tell your media handler about changes to either the movie matrix or the track matrix.
pascal ComponentResult MediaSetMatrix (MediaHandler mh,
MatrixRecord *trackMovieMatrix);
The Movie Toolbox calls your derived media handler's MediaSetMatrix function whenever either the movie matrix or track matrix changes. The toolbox provides you with a matrix that concatenates the transformations defined by both the movie and track matrices. You can use this matrix to map your media's display representation into the movie's coordinate system. For example, by applying this matrix to the track rectangle, you can determine the display boundaries of your media (the track rectangle is defined by the width and height fields in the movie parameter structure that you obtain when the toolbox calls your MediaInitialize function).
You obtain the initial matrix from the trackMovieMatrix field of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
Your derived media handler should support this function if you draw during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function (described on MediaSetHandlerCapabilities ).
Before you try to use this matrix, you should make sure that your media handler can accommodate its transformations. You can use the Movie Toolbox's GetMatrixType function to learn about the matrix. If the matrix includes transformations that are beyond the capabilities of your media handler, you can direct the base media handler to do display processing on your behalf. Call the MediaSetHandlerCapabilities function and set the handlerNeedsBuffer flag to 1 in the flags parameter. This forces the base media handler to draw your media into an offscreen buffer.
The Movie Toolbox uses the MediaSetDimensions function to tell your media handler about changes to the rectangle that surrounds the graphical representation of your media; this function is described in the previous section. In addition, your media handler's MediaSetClip function allows you to learn about changes to your media's clipping region. This function is discussed next.
The MediaSetClip function allows your derived media handler to learn about changes to its clipping region.
pascal ComponentResult MediaSetClip (MediaHandler mh,
RgnHandle theClip);
The Movie Toolbox calls your derived media handler's MediaSetClip function whenever the track's clipping region changes. The toolbox provides you with a handle to a clipping region that supersedes any other clipping region you may be using.
Your derived media handler should support this function if you draw during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial and handlerCanClip flags to 1 in the flags parameter of the MediaSetHandlerCapabilities function (described on MediaSetHandlerCapabilities ).
The MediaGetTrackOpaque function allows the Movie Toolbox to determine whether your media is transparent or opaque when displayed.
pascal ComponentResult MediaGetTrackOpaque (MediaHandler mh,
Boolean *trackIsOpaque);
The Movie Toolbox uses this function when it is building a movie from composited images. Your media handler returns information that tells the toolbox whether your media's displayed image is to be combined with other images that are already on the screen. If you draw your media in blend mode, for example, your media is semitransparent, and its display relies upon other images on the screen. The Movie Toolbox needs to know this in order to correctly display the movie to the user.
Your derived media handler should support this function if your media is semitransparent when displayed or if you handle display transfer modes.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial or handlerCanTransferMode flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.
The MediaGetNextBoundsChange function allows the Movie Toolbox to determine when your media causes a spatial change to the movie.
pascal ComponentResult MediaGetNextBoundsChange
(MediaHandler mh,
TimeValue *when);
The Movie Toolbox uses this function to determine when the next spatial change will occur in the current movie. Your media handler returns a time value. Your media handler must examine the edit list of the track that contains your media in order to derive this duration. You can use the Movie Toolbox's GetTrackNextInterestingTime function to retrieve time values in the movie's time coordinate system. For details on this function and on movie time values, see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime .
Your derived media handler should support this function if you change the shape of your media's spatial representation during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.
The MediaGetSrcRgn function allows your derived media handler to specify an irregular destination display region to the Movie Toolbox.
pascal ComponentResult MediaGetSrcRgn (MediaHandler mh,
RgnHandle rgn,
TimeValue atMediaTime);
The Movie Toolbox uses this function to determine whether your media has an irregularly shaped display area. If your media is displayed in a nonrectangular area, or if your media uses only a portion of the track rectangle, you can use this function to report that fact to the toolbox.
Your derived media handler should support this function if your media does not completely fill the track rectangle during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.